C/C++ Users Group Library 1996 July

home *** CD-ROM | disk | FTP | other *** search

/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_300 / 339_01 / ctrlcdoc.exe / CTRLCMAN.DOC

Wrap

Text File | 1990-12-15 | 163KB | 4,361 lines

--== C T R L C L I B ==-- The Ctrl+C Library A C-language Library of Integrated Interrupt Management Functions USER'S GUIDE and REFERENCE MANUAL Version 1.0 _______ ____|__ | MEMBER --| | |------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals -----| | |--------------------- |___|___| (R) Copyright (C) 1990 Trendtech Corporation, Wayne, NJ, All Rights Reserved Licensed Material - Program, Documentation, and Text Files are Property of Trendtech Corporation. Page 2 CTRLCLIB - The Ctrl+C Library COPYRIGHT NOTICES AND TRADEMARKS CTRLCLIB - The Ctrl+C Library(Tm) is Copyright 1990 by Trendtech Corporation, Inc., Wayne, New Jersey, U.S.A. All rights reserved. Licensed Material; this collection of software objects, its documentation, demo programs, other accompanying written and disk-based notes and specifications, and all referenced and related program files, are the property of Trendtech Corporation, Inc., Wayne, NJ, U.S.A. -CTRLCLIB - The Ctrl+C Library is a trademark of Trendtech Corporation, Inc., Wayne, NJ. -The ASP and logo are registered trademarks of the Association of Shareware Professionals. -CompuServe is a registered trademark of CompuServe Incorporated. -DESQview is a trademark of Quarterdeck Office Systems. -IBM is a registered trademark of International Business Machines. -Microsoft is a registered trademark of Microsoft Corporation. -Turbo C is a registered trademark of Borland International. -QuickC is a trademark of Microsoft Corporation. CTRLCLIB is distributed as Shareware and has specific licensing provisions, please read the following sections for more information about Shareware, licensing, and registration procedures. Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subdivision (b)(3)(ii) of the Rights in Technical Data and Computer Software clause at 252.227-7013. EVALUATION NOTE: Space limitations on the Shareware disk allow only two memory-model libraries for each compiler. If you can not fully evaluate CTRLCLIB because of the lack of a specific memory model such as "compact" or "medium", please contact us. We will supply you with a disk containing a library for the memory-model you need for the compiler you specify. This disk will be supplied to you free of charge so that you may thoroughly evaluate CTRLCLIB. _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 3 CTRLCLIB - The Ctrl+C Library T A B L E O F C O N T E N T S ____________________________________________________________ 1. REGISTRATION 5 2. SUPPORT 5 2.1 Technical Support 5 2.2 Electronic Support 6 2.3 Telephone and Mail Support 6 3. ACKNOWLEDGEMENTS 7 4. INTRODUCTION 8 4.1 What Can I Do With CTRLCLIB? 10 4.2 What Took So Long? 11 4.3 The Mechanics of CTRL-C and CTRL-BREAK 12 4.4 Our Solution - an Intelligent INT09 16 5. USING CTRLCLIB EFFECTIVELY 16 5.1 Technicals 16 5.2 Operation 17 5.3 Using Library Functions 17 5.4 The Interrupt Management Control Structure 18 5.5 Code Examples 18 6. LIBRARY DISTRIBUTION 20 6.1 The Shareware Disk 21 6.2 The Registered Source Disk 23 7. INSTALLING CTRLCLIB 24 7.1 Installation 24 7.2 Compiling 25 7.3 Linking 25 8. GENERAL NOTES 25 8.1 Borland Turbo C Notes 26 8.2 Microsoft C Notes 27 8.3 Microsoft QuickC Notes 27 8.4 MS-DOS Notes 27 8.5 General Caveats 28 8.5.1 Keyboard Idiosyncrasies 28 8.5.2 Virtual Control Programs 29 8.5.2.1 WINDOWS, DESQview, VM386, OS/2, et al 29 8.5.3 Other Caveats 30 8.5.3.1 TSR's 30 8.6 Making Changes 31 8.7 Feedback 31 9. FUNCTION CALL REFERENCE SECTION 32 9.1 int BreakFlag( action, flagset ) 33 9.2 int CapsLock( setting ) 34 9.3 int CtrlcLibSetup(varg) 36 9.4 void CtrlcLibCleanup( void ) 38 9.5 void CtrlAltDel( action ) 39 9.6 void CtrlBreak( action ) 40 _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 4 CTRLCLIB - The Ctrl+C Library 9.7 void CtrlC( action ) 41 9.8 void CtrlP( action ) 42 9.9 void CtrlS( action) 43 9.10 void FullCtrlC( action ) 44 9.11 int InsertLock( setting) 45 9.12 void KeyboardHandler( action ) 47 9.13 int NumLock( setting ) 48 9.14 void PauseKey( action ) 50 9.15 void PrintScreen( action ) 51 9.16 unsigned QueryCtrlC(void) 52 9.17 unsigned QueryKeyPad5(void) 53 9.18 unsigned QueryPrtScr(void) 54 9.19 unsigned QuerySysReq(void) 55 9.20 int ScrollLock( setting ) 56 9.21 void ShowCtrlC( void) 58 9.22 void SysReq( action ) 59 9.23 void SystemReset( action ) 60 10. APPENDIX -A- LICENSE AND REGISTRATION 61 10.1 SHAREWARE LICENSE 61 10.2 Warranty and Liability Information. 62 10.2.1 Shareware Version - Warranty Exclusion 62 10.2.2 Registered Version - Limited Warranty 62 10.2.3 Liability Limitation 63 10.3 REGISTRATION 63 10.3.1 Source Code 63 10.3.2 Single-User License 64 10.3.3 Network License. 65 10.3.4 Site License 66 10.3.5 Retail Distribution 66 10.3.6 Sales Tax: 66 10.4 OWNERSHIP 66 11. APPENDIX -B- WHAT IS SHAREWARE 67 12. APPENDIX -C- DISTRIBUTION REQUIREMENTS 68 13. APPENDIX -D- REGISTRATION BENEFITS 69 13.1 Upgrade Policy 69 14. APPENDIX -E- THE A.S.P. 70 14.1 The ASP Ombudsman Statement 70 14.2 Summary of ASP Goals 70 14.3 ASP Standards for Author Members 71 14.3.1 PROGRAMMING STANDARDS 71 14.3.2 DOCUMENTATION STANDARDS 71 14.3.3 SUPPORT STANDARDS 71 14.3.4 GENERAL 72 _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 5 CTRLCLIB - The Ctrl+C Library 1. REGISTRATION CTRLCLIB and all programs and documentation distributed or shipped with it are copyrighted works protected by U.S. and international copyright laws. This collection of programs and files is referred to simply as "CTRLCLIB". You are granted a license to use your evaluation copy of CTRLCLIB only under the terms and conditions specified in APPENDIX -A- of this document. CTRLCLIB is a commercial software package. It is not free, and it is not in the public domain. It is distributed as Shareware, which means that before you pay for the package, you may try it and see if you want to continue using it. You may use CTRLCLIB free for a trial period of up to 30 days. If you wish to continue using CTRLCLIB after that period, you must pay a registration fee. If you choose not to pay the registration fee, you must stop using CTRLCLIB and remove it from your computer, though you are still free to keep copies and pass them along to others. Please read the APPENDIX for complete license and registration details. 2. SUPPORT 2.1 Technical Support We support our software. One of the great strengths of the Shareware concept is the direct interaction between the program author and the users. Many of the current features in CTRLCLIB are the result of user input. If you have a problem evaluating the components of this library or desire to make a suggestion or comment (or even a complaint), please don't hesitate to contact us. Technical support for CTRLCLIB is available to both shareware and registered users. If you are not a registered user, we will provide limited assistance to help you install and evaluate CTRLCLIB . You may call or write us for technical support. Unless your problem is relatively complex, you will get the best results by calling. If you write us, please include a phone number and the times when you will be available. Most of the time you'll get our answering machine, so please speak clearly and slowly when you leave your name and telephone number. _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 6 CTRLCLIB - The Ctrl+C Library With reference to calls, if we do not call back, please remember that a small percentage of our call-backs do not get completed because of faulty phone numbers, unanswered, or busy phones, or a garbled answering machine message. If we have not called you back within one work day, please call us again. 2.2 Electronic Support Electronic support is available on CompuServe. CompuServe electronic correspondence is limited to electronic mail only. Our MAIL ID is [76210,771]. If you wish to find out more about the Shareware concept and talk electronically to other Shareware authors, we encourage you to join the SHAREWARE forum on Compuserve. After logging in to CIS, simply type "GO SHAREWARE". This will put you in the IBMJR forum. Don't be alarmed however, as of this writing, CompuServe has not yet changed the forum name to "SHAREWARE", it is still called "IBMJR". Author-members of the Association of Shareware Professionals have been allocated sections 8, 9, 10, 11, and 12. Sections 8 and 9 are open to the general public. We occasionally check other forums (SIG's) too but these should not be considered a vehicle for effective communication to Trendtech. If you are a CompuServe user and you need to reach us, please use electronic MAIL. Most of the time MAIL messages are answered on a daily basis. If you need information on obtaining a CompuServe account you can call CompuServe toll free at 1-800-848-8199. 2.3 Telephone and Mail Support We can be reached via U.S. Mail at: TRENDTECH CORPORATION P.O. Box 3687 Wayne, New Jersey 07474-3687 U.S.A. by FAX: (201) 694-2543 by VOICE: (201) 694-8622 For voice, please leave a message; as stated above, we try to respond to telephone messages as quickly as possible, but may require 24 hours or more depending on our workload and the timing of your call. _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 7 CTRLCLIB - The Ctrl+C Library 3. ACKNOWLEDGEMENTS Trendtech Corporation would like to thank all who participated in Alpha and Beta testing of CTRLCLIB. We'd especially like to thank Dave Jurgens, Tracey Siesser, Walt Myers, Hans Salvisberg, Mike Vore, Roger Baird, Kenneth Loafman, Carl Huff, Larry Weaver, and others who provided thoughtful insight into potential problems, offered solutions, and tendered new ideas for possible enhancements. Your efforts are greatly appreciated. _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 8 CTRLCLIB - The Ctrl+C Library ---==<< CTRLCLIB - THE CTRL+C LIBRARY >>==--- 4. INTRODUCTION What do you think would happen to your application program or the database files it has opened if the user accidently (or on purpose) hit the CONTROL-C or CONTROL-BREAK keys? Or, suppose they pressed CTRL+ALT+DEL in the middle of a complicated file update? These keys will terminate your program, we all know that. But what about the CTRL+2 keys (the CTRL key plus the number row "2" key)? Or, how about the "back-door" ALT+kp3 (the ALT key plus the keypad 3 )? If the user accidently pressed these keys, they will cause your program to come to a screeching halt too just as well as the more straight-forward control-c and control-break keys. If your program doesn't use standard console input and output you might be okay. But, suppose the user placed "BREAK ON" in their CONFIG.SYS file? This means that DOS will check for the break keys on a wider variety of DOS functions than just console I/O, so your program could 'crash and burn' anyway. If part of your application is keyboard intensive such as a complicated data-entry program, then you'd probably want to make your program "user-proof". If users wanted to "break out" of your program, it should be robust enough to detect that action, and then "gracefully" terminate. We say "gracefully" because this will give your application program a chance to do its final "cleanup" before ending. With CTRLCLIB in your toolbox of professional software development tools, you can provide the robustness your applications need to make them fully user-proof. To paraphrase a famous line from a popular science-fiction TV show of years ago: "YOU CAN CONTROL THE VERTICAL, YOU CAN CONTROL THE HORIZONTAL". In other words, you can fully direct the course of action your program can take in response to user-initiated interrupts. _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 9 CTRLCLIB - The Ctrl+C Library CTRLCLIB is a C-language library of integrated interrupt management functions that commercial software developers, system designers, and programmers can use to help make their programs "user-proof". With as little as a simple one-time call to one or more functions from the library, you can set up interrupt handlers and traps to block keystroke combinations that would normally cause most programs to terminate unexpectedly. But let's face it, no program is completely user-proof - there is always the power-OFF switch. But short of that however, with functions from CTRLCLIB you can "catch" many inappropriate keypresses by users of your application program. For example, if your application is a complicated word-processor or editor, you'd want to ask the user to save changed files before they accidently (or purposely) pressed the CTRL+C or CTRL+BREAK keys that normally terminates any MS-DOS program. If you're designing a sophisticated windowing application, you don't want the insidious "^C" characters botching up your windows when the user accidently pressed <ALT>+<keypad 3> or <CTRL>+<number 2>. Yes, these too are program break keys. By including routines from CTRLCLIB you can insure that your application is well protected from anxious users who press keys indiscriminately. With support functions from CTRLCLIB, your program can control the setting of the LOCK keys too. If the data entry procedures in your application need to have the NUM LOCK key "ALWAYS" ON, for example, just call a CTRLCLIB library function once, and from then on, the NUM LOCK will remain ON, the user cannot turn it off. When your data entry function is finished, just call a function from CTRLCLIB to turn it off. The same goes for the other LOCK keys too. If your application is time-critical and you don't want the user messing with the PAUSE key or CTRL+S, simply call a function from CTRLCLIB to disable it. CTRLCLIB is a collection of C-language functions that replace interrupt handlers as needed and removes them when they are not needed - all controlled by you - the application developer. And best of all, the entire library is written in C, there is NO assembly language, so you don't need MASM or Debug. _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 10 CTRLCLIB - The Ctrl+C Library 4.1 What Can I Do With CTRLCLIB? The functions in CTRLCLIB can help your application program manage a discreet class of interrupts. For the most part these consist of the interrupts that are initiated by the user and are caused by unique keystroke combinations made while they are running your application program. The following list illustrates the kinds of interrupts that your program can catch using functions from CTRLCLIB: KEYPRESS INTERRUPT: What it normally does: ============================================================ o CTRL+BREAK and CTRL+C - Program termination o CTRL+2 and ALT+Keypad 3 - Program termination o The "^C" screen print - Disrupts screen display o CTRL+ALT+DEL - System reset o PRINT SCREEN - Screen dump to printer o CTRL+PRTSCRN and CTRL+P - Screen echo to printer o PAUSE KEY or CTRL+NUML - System pause until keystroke o CTRL+S - Pause MS-DOS output to STDOUT Callable functions from CTRLCLIB can disable any or all of the above keypress interrupts. Your application program can also exercise a high degree of control over the following keyboard keys with functions from CTRLCLIB: o CAPS LOCK KEY - Full control o NUM LOCK KEY - Full control o SCROLL LOCK KEY - Full control o INSERT LOCK KEY - Full control o KEYPAD 5 KEY - Full keypress detection _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 11 CTRLCLIB - The Ctrl+C Library Full control options: ALWAYS-ON, ALWAYS-OFF, ON, OFF, TOGGLE Your application can have the following support functions available as needed: o REBOOT - Initiate a WARM or COLD reboot anytime o DISPLAY THE "^C" CHARACTERS - when YOU want o QUERY functions - determine if user pressed any of the interrupt keys. 4.2 What Took So Long? Over the years there have been many articles written in computer magazines, newsletters, and books about ways to trap various critical keypresses such as control-break and control-c. Some of these articles illustrated how to trap these keys in BASIC, Assembly, and even C. Many so-called "advanced" programming language books addressed the issue too. Some even provided sample code to trap certain keystrokes and to install Interrupt Service Routines (ISR's). There are also expensive commercial C-language libraries that contain a few functions to handle some of these critical keypresses. Most of what was written, and most of what is currently sold in expensive libraries only skimmed the surface or skirted the more important issues of interrupt management. Almost all of the methods illustrated lacked one critical element; they failed to provide feedback to the program when these keys were pressed. A truly robust program should know if a user wants to get out but doesn't know how so they hit the break keys. Until now, no one has ever addressed the issues of FULL user-caused interrupt management control, especially with respect to Ctrl-C and Ctrl-Break protection. Yes, it's easy enough to trap these keys and prevent program termination, but it's NOT easy to stop MS-DOS from throwing up the insidious " ^C " characters on the screen. This can be caused in a variety of ways. David Burki succinctly addressed the issue in an article entitled "Eliminating Control-C" in the August 1990 issue of TECH SPECIALIST Vol. 1 Number 3. David has graciously approved, and R & D Publications has granted us permission to reprint most of his article in this CTRLCLIB User's Guide. _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 12 CTRLCLIB - The Ctrl+C Library With CTRLCLIB - The Ctrl+C Library, we want to "pull it all together" and create a programming support library - a central repository, if you will, of interrupt management control. CTRLCLIB is the result of an extensive effort to create an integrated set of interrupt management functions written entirely in C, and callable from any program. Our goal is to make CTRLCLIB the definitive MS-DOS standard for managing user- initiated program interrupts. 4.3 The Mechanics of CTRL-C and CTRL-BREAK The following description of the control-c and control-break process was written by David Burki and appeared in the August 1990 issue of Tech Specialist. Additionally, the article included David's assembly language implementation of an INT16H interrupt handler to intercept control-c and the "^C" characters. In the interest of space, that portion has been dropped. Full reprints may be obtained from R & D Publications - see address and phone number below. The following is an edited version of David's article: _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 13 CTRLCLIB - The Ctrl+C Library Eliminating Control-C by David Burki The standard "solutions" to preventing Ctrl-C and Ctrl- Break from abnormally terminating an application program all deal with replacing the 23H and 1bH interrupt vectors. While it is true that replacing these vectors with your own handler can prevent the user from terminating the program by pressing Ctrl-C or Ctrl-Break, what do you do about the annoying, unesthetic ^C that DOS puts on the screen? One method of preventing the ^C from appearing on the screen is to locate the hardware cursor at some non- displayed location like row 26. This strategy works great until you either want to display the hardware cursor or use a DOS screen output function. BACKGROUND An int 21H generally causes internal DOS housekeeping code to check the next available key in the keyboard buffer, using the BIOS interrupt 16H function 1. If the next available keycode is 2e03H (the scan and ASCII code for Ctrl-C), or the DOS Ctrl-Break flag is 3 (more on the flag in a minute), DOS puts the ^C on the screen, flushes the keyboard buffer, switches to the user stack, clears the carry flag, and executes interrupt 23H. Among other things, the default interrupt 23H handler flushes the file buffers using function 0dH of interrupt 21H. The 23H handler then sets the carry flag and returns with a RET 2. When the housekeeping code regains control, it uses the carry flag to determine if it should terminate the process (function 4cH of interrupt 21H) or continue with the execution of the interrupted function. If your application keeps the typeahead buffer empty by using BIOS function calls, DOS may never get a chance to see a CTRL-C. However, a user might still be able to sneak one in, especially if your application makes DOS function calls that write to the screen. _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 14 CTRLCLIB - The Ctrl+C Library Ctrl-Break is recognized within the keyboard hardware interrupt, BIOS int 9. When int 9 detects the Ctrl-Break key combination, code within interrupt 9 first flushes the keyboard buffer and then executes an interrupt 1bH. By default, the code pointed to by the interrupt 1bH vector contains only two instructions: MOV CS:[FLAG],3 IRET The first instruction sets the internal DOS flag, mentioned earlier, to indicate Ctrl-Break has been pressed. The IRET returns to the BIOS keyboard interrupt. DOS examines the internal DOS flag during its housekeeping code to determine if Ctrl-Break has been pressed. If the internal DOS flag equals 3, DOS runs the same code that executes when Ctrl-C is detected. A quick session with Debug shows that if you set the internal DOS flag byte to 3, DOS places the ^C on the screen at the current cursor location and executes an INT 23H. Since the DOS interrupt 1bH handler is called from the keyboard hardware interrupt, it must be replaced in order to prevent Ctrl-Break from displaying ^C on the screen. Flagging Ctrl-Break is an asynchronous event. Therefore, Ctrl-Break may interrupt a program's execution when Ctrl-C won't. For Ctrl-C to be recognized, the Ctrl-C keycode has to be at the head of the keyboard buffer when the DOS housekeeping process is executing. Ctrl-Break on the other hand, immediately sets the internal DOS break flag, which will be checked the next time the DOS housekeeping process is executed. Following is the pseudocode for the section of interrupt 21H which does the checking for Ctrl-C and Ctrl-Break. FLAG is the DOS internal variable interrupt 1bH sets to 3 and NEXT_KEY is the value returned in AX by interrupt 16H function 1. if FLAG equals 3 OR NEXT_KEY equals CTRL_C then print "^C" flush keyboard buffer switch to user stack clear carry flag execute INT 23h change back to DOS stack if (carry set) then terminate program else _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 15 CTRLCLIB - The Ctrl+C Library continue interrupted DOS function endif In the BIOS System Data Area you can find a byte at 40:71H called the Break Flag. According to the comment in the BIOS listing, this byte flag will have bit 7 set by the BIOS interrupt 9 handler when Ctrl-Break has been pressed and the BIOS listing for interrupt 9 clearly shows bit 7 being set. If you explore the BIOS code with Debug you'll see that once set, bit 7 is never cleared. The BIOS Break Flag is ignored by DOS. Once set by interrupt 9, it stays set. [David then describes his implementation of a Ctrl-c and Ctrl-Break handler written in assembler. David's approach is to override the INT16H keyboard handler to solve the ^C problem.] A SOLUTION [In summary], you [can] replace the interrupt 1bH vector with an IRET instruction to prevent DOS from displaying the ^C on the screen when Ctrl-Break is pressed, and DOS won't even know it happened. Ctrl-C, on the other hand, involves hiding from DOS the Ctrl-C returned by the BIOS. There are advantages to filtering the return values of interrupt 16H as a means of controlling Ctrl-C. As I demonstrated, the ^C won't show up on the screen. You can have a flag set for your favorite high-level language to examine, or with a little more effort, you can convert Ctrl-C for use as a valid key combination for your application. You have control! ----------------- Reprinted by permission from TECH Specialist, vol. 1, no. 3, August 1990, for Trendtech Corporation. Copyright 1990 by R&D Publications, 2601 Iowa Street, Lawrence, KS 66046 (913) 841-1631. [Biography]: David Burki is a consultant and author. He specializes in systems and application software design and development under MS- DOS using C and Assembly language. Projects include the development of a sales analysis database for a major chemical company and the design and development of a quality assurance/patient tracking database for trauma center hospitals. David may be contacted through us; call (201) 694-8622. _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 16 CTRLCLIB - The Ctrl+C Library 4.4 Our Solution - an Intelligent INT09 We've taken a different approach to solving the control-c, control-break, and "^C" print problem. The gem of CTRLCLIB is our implementation of an INT09H keyboard handler. In addition to detecting Ctrl-C and other keystrokes, plus the "broadsiding" keystrokes that cause the insidious "^C" characters to appear in STDOUT, our INT09H implementation also handles most of the other features and functions of CTRLCLIB. The communications device between the various functions and our keyboard handler is a control structure contained in a "header" file called CTRLC.H. Our INT09H handler will intercept only the keystrokes you want trapped based on CTRLCLIB functions your application program calls and the flag settings they communicated to the control structure. We chose to use INT09H over INT16H so that we could provide software developers with absolute control over the behavior of their programs. Many TSR's trap INT09 looking for their "hot" keys. This allows the TSR to manipulate the keystrokes BEFORE your program gets them. If you implemented INT16H to capture critical keystrokes, you couldn't be sure what was done with them before your handler intercepted them. That's not to say that some future TSR might use functions from CTRLCLIB; nevertheless, since your application is normally loaded AFTER TSR's, your program would STILL get first crack at the users' keystrokes. We think this is what you want. 5. USING CTRLCLIB EFFECTIVELY 5.1 Technicals CTRLCLIB supports PC/MS-DOS for the IBM PC/XT/AT, PS/2 and 80286 and 80386 compatibles. However, you'll need one of the following compilers so your application can take advantage of the benefits available in the Library: Microsoft C Microsoft Quick C Borland Turbo C and C++ CTRLCLIB is written entirely in "C"; there is absolutely NO assembly language for you to fool with. You just need one of the C-compilers mentioned above to take full advantage of the functions in CTRLCLIB. _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 17 CTRLCLIB - The Ctrl+C Library 5.2 Operation Simply include the functions you need in your source code at compile-time, plus CTRLCLIB that's specific to your compiler and memory model size at link-time. That's all there is to it. 5.3 Using Library Functions The easiest way to implement interrupt management functions from CTRLCLIB is with a single call to the CtrlcLibSetup(...) function placed at the beginning of your program. You specify the traps and interrupts that your application is to control by writing their CONSTANT names and "OR'ing" them together as a single argument to the CtrlcLibSetup() function call. Example: CtrlcLibSetup( FCTRLC | PAUSEKEY | PRINTSCREEN ) The function call to CtrlcLibSetup() given in this particular example will extend full control over the Control- Break/Control-C program termination keypresses, including accidental keypresses of Control-2 or ALT-3 (which also cause program termination). Additionally, it will automatically reset the PAUSE flag when the keyboard PAUSE key (CTRL+NUMLOCK on some keyboards) is pressed, and deactivate the Print Screen key. That's it. One function call. You'll also want to make sure all of the traps and interrupts that your program sets are cleared before program termination. This can be done with a single call to CtrlcLibCleanup(). This function will look through the interrupt management control structure and reset all traps and interrupts that it finds were previously set by the CtrlcLibSetup() function call. This is important because if your program does not properly reset some interrupt vectors when it terminates, the interrupt vectors will be pointing to an area of memory which may no longer contain the altered vector's code. In most cases, this will "hang" the user's system. The only solution is a cold-boot. _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 18 CTRLCLIB - The Ctrl+C Library 5.4 The Interrupt Management Control Structure Communication between the installed interrupts, other CTRLCLIB functions, and your application program is accomplished by setting values in a control structure which is #include'd in your program at compile time. You don't set values, the functions you call from CTRLCLIB do. The header file is called CTRLC.H and must be included in any source module which calls functions from CTRLCLIB. Additionally, the source module which defines and initializes the variables are contained in module CL_COMM.C. There's no need to add any special code to get the functions to work. 5.5 Code Examples The following example shows the minimum code requirements for using functions from CTRLCLIB: _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 19 CTRLCLIB - The Ctrl+C Library Main source module: #include <stdio.h> #define MAINL /* required in MAIN() source only*/ #include "ctrlc.h" /* required header */ main() { CtrlcLibSetup( FCTRLC | CTRLP | PAUSEKEY ); . . . (your application code) . if (program_error()) { CtrlcLibCleanup(); abort(); } . . . CtrlcLibCleanup(); exit(0); } Subsequent source module: #include "ctrlc.h" /* required header */ int program_error(void) { (more code) . . if (QueryCtrlC() == CTRLC) /*user pressed ctrl-c*/ return(1); /*(these tests are optional)*/ . . . return(0); } _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 20 CTRLCLIB - The Ctrl+C Library Notice the first module declares and defines the main() function. This is where the programmer decided to #define MAINL, causing the interrupt control structure in CTRLC.H to be declared and allocated memory. The subsequent source module uses a query function from CTRLCLIB thus requiring the inclusion of the CTRLC.H header. Notice too that in the subsequent module MAINL is not defined, causing the interrupt control structure in turn to be defined as EXTERN. The address of the interrupt management control structure is resolved at link-time. Both the Shareware disk and the Registered disk have the source code for the CTRLC.H header. You can examine this file to see how this is accomplished. 6. LIBRARY DISTRIBUTION CTRLCLIB is distributed on floppy diskettes for both the Shareware version and the Registered version. The Registered version contains full source code and two additional memory model libraries. This document describes both versions. Neither version contains ALL of the files listed below. The Shareware evaluation diskette can be freely copied and shared. The Registered, number-serialized disks contain source code and can not be shared or distributed. In either case you receive a fully functional "bundled" product. That is to say, we do not require you to order a separate disk for the Microsoft compiler, another for the Borland compiler, and so on. You get ready-made libraries for all supported C compilers. CTRLCLIB is supported for all the C compilers we specify. This makes porting your code from one compiler to another a very easy process. It also helps to protect your application software development investment while at the same time saving you a significant sum of money! _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 21 CTRLCLIB - The Ctrl+C Library 6.1 The Shareware Disk The Shareware version of CTRLCLIB is distributed on a single 360k diskette. It contains libraries for the small and medium models for use with the Microsoft C compiler, the Microsoft Quick-C compiler, and Borland's Turbo-C and C++ compilers. The Shareware disk contains the following files: README.1ST <- Latest information and what to do MSC5SH.ZIP <- Microsoft 5.1 archive library MSC6SH.ZIP <- Microsoft 6.0 archive library QC25SH.ZIP <- Microsoft Quick-C 2.5 archive library TC20SH.ZIP <- Borland Turbo-C 2.0 archive library TCXXSH.ZIP <- Borland Turbo-C++ 1.0 archive library QUICKREF.DOC <- Summary of function calls CTRLCDOC.EXE <- The User's Manual-self extracting CLDEMO.EXE <- Demo program BOOTDEMO.EXE <- System Reset demo program CTRLC.H <- CTRLCLIB header file CLDEMO.C <- Source code for Demo program BOOTDEMO.C <- Source code for reboot program HISTORY.DOC <- Revision history REGISTER.FRM <- Registration form VENDOR.DOC <- Distribution notes for disk vendors SYSOP.DOC <- Distribution notes for BBS sysops Each ZIP file contains two memory-model libraries, a 'MAKE' file for building the two demo programs, and a batch file for invoking the make program of your choice. Contents of MSC5SH.ZIP (for Microsoft C Version 5.1) COMPMSC5.BAT <- Batch program to invoke MAKE MSC5.MAK <- MAKE file for Microsoft C 5.1 compiler SMSC5CL.LIB <- Ctrl+C Library - small memory model LMSC5CL.LIB <- Ctrl+C Library - large memory model Contents of MSC6SH.ZIP (for Microsoft C Version 6.0) COMPMSC6.BAT <- Batch program to invoke MAKE MSC6.MAK <- MAKE file for Microsoft C 6.0 compiler SMSC6CL.LIB <- Ctrl+C Library - small memory model LMSC6CL.LIB <- Ctrl+C Library - large memory model Contents of QC25SH.ZIP (for Microsoft Quick-C Version 2.5) COMPQC25.BAT <- Batch program to invoke MAKE QC25.MAK <- MAKE file for MS Quick-C 2.5 compiler SQC25CL.LIB <- Ctrl+C Library - small memory model _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 22 CTRLCLIB - The Ctrl+C Library LQC25CL.LIB <- Ctrl+C Library - large memory model Contents of TC20SH.ZIP (for Borland Turbo-C Version 2.0) COMPTC20.BAT <- Batch program to invoke MAKE TC20.MAK <- MAKE file for Turbo C 2.0 compiler STC20CL.LIB <- Ctrl+C Library - small memory model LTC20CL.LIB <- Ctrl+C Library - large memory model Contents of TCXXSH.ZIP (for Borland Turbo-C++ Version 1.0) COMPTCXX.BAT <- Batch program to invoke MAKE TCXX.MAK <- MAKE file for Turbo C++ 1.0 compiler STCXXCL.LIB <- Ctrl+C Library - small memory model LTCXXCL.LIB <- Ctrl+C Library - large memory model Contents of CTRLCDOC.EXE CTRLCMAN.DOC <- Complete User Guide and Reference Manual _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 23 CTRLCLIB - The Ctrl+C Library 6.2 The Registered Source Disk Registered users will receive a number-serialized disk containing the full source code, plus libraries for the compact and medium memory-model for supported compilers. Additionally, the disk will contain batch and make files for compiling all of the source code and building each of the libraries. The registered disk contains the following files: README.2ND <- Latest information and what to do SERIAL.NBR <- Registrant's serial number LICENSE.DOC <- Licensing information MSC5REG.ZIP <- Microsoft 5.1 additional archive library MSC6REG.ZIP <- Microsoft 6.0 additional archive library QC25REG.ZIP <- Microsoft Quick-C 2.5 additional library TC20REG.ZIP <- Borland Turbo-C 2.0 additional library TCXXREG.ZIP <- Borland Turbo-C++ 1.0 additional library CLSOURCE.ZIP <- The full source code archive CTRLCDOC.EXE <- The User's Guide-self extracting HISTORY.DOC <- Revision history Contents of CLSOURCE.ZIP All source code for components of CTRLCLIB. Contents of CTRLCDOC.EXE CTRLCMAN.DOC <- Complete User Guide and Reference Manual Contents of MSC5REG.ZIP (for Microsoft C Version 5.1) CMSC5CL.LIB <- Ctrl+C Library - compact memory model MMSC5CL.LIB <- Ctrl+C Library - medium memory model Contents of MSC6REG.ZIP (for Microsoft C Version 6.0) CMSC6CL.LIB <- Ctrl+C Library - compact memory model MMSC6CL.LIB <- Ctrl+C Library - medium memory model Contents of QC25REG.ZIP (for Microsoft Quick-C Version 2.5) CQC25CL.LIB <- Ctrl+C Library - compact memory model MQC25CL.LIB <- Ctrl+C Library - medium memory model Contents of TC20REG.ZIP (for Borland Turbo-C Version 2.0) CTC20CL.LIB <- Ctrl+C Library - compact memory model MTC20CL.LIB <- Ctrl+C Library - medium memory model Contents of TCXXREG.ZIP (for Borland Turbo-C++ Version 1.0) CTCXXCL.LIB <- Ctrl+C Library - compact memory model MTCXXCL.LIB <- Ctrl+C Library - medium memory model _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 24 CTRLCLIB - The Ctrl+C Library 7. INSTALLING CTRLCLIB 7.1 Installation 1) Please! MAKE A BACKUP OF ALL DISKS before you do anything else!!! 2) For installation on a hard drive, make a directory called \CTRLC and copy the files from both diskettes to it. Important files do NOT have duplicate names; even the readme's are different. 2) a. SHAREWARE diskette - Use PKUNZIP to unarchive the various ZIP files. There is a ZIP file for each supported compiler. You will need about 400k of free disk space for all of the files! Alternatively you can extract only those files you need for use with a specific compiler. Simply use PKUNZIP to extract the files from each xxxxSH.ZIP file, for example: C> A:PKUNZIP E A:MSC5SH SMSC5CL.LIB gets you the small model library for the Microsoft C Version 5.1 compiler. These library files contain the SMALL and LARGE models. b. REGISTERED Source Code diskette - Use PKUNZIP to unarchive SOURCE.ZIP. Then, depending upon the compiler and memory model you intend to use, unarchive one or more of the following ZIP'd library files: MSC5REG.ZIP, MSC6REG.ZIP, QC25REG.ZIP, TC20REG.ZIP, or TCXXREG.ZIP. If you plan on unarchiving all of the compiler specific ZIP files you will need approximately 800K of free disk space! These library files contain the MEDIUM and COMPACT models. 3) Copy the Library that corresponds to the compiler and memory model you are using onto the disk partition and directory that you usually use with your "C" compiler. The .LIB file should be on the same disk partition and directory that the "C" runtime libraries are on. _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 25 CTRLCLIB - The Ctrl+C Library 4) Remember there is no magic to using CTRLCLIB to make your programs user-proof. Just a few simple steps is all you need. 7.2 Compiling Compile your source code using whichever method suites you best. If you're using an integrated development environment or a programmers workbench make sure you specify the path to the CTRLC.H header file. If you're using the full compiler with MAKE files make sure your environment variables and/or make file macros point to the path where CTRLC.H and the .LIB files can be found. 7.3 Linking Simply specify the xxxxCL.LIB file that corresponds to the compiler/memory model you are using. Don't forget to include your compilers runtime library as well. The following examples demonstrate basic linking using the small model library. Microsoft (C & Quick C): link cldemo,cldemo,,smsc5cl Borland Turbo C: tlink /c c0s cldemo,cldemo,cldemo,stc20cl emu maths cs 8. GENERAL NOTES It is important here to note that when you incorporate functions from CTRLCLIB into your program that you do so at the end of your development and debugging cycle. Functions from CTRLCLIB should be activated when you are confident that your program will run without aborting or terminating abnormally. It this happens, and your program has not restored the interrupt handlers, you will almost ALWAYS have to reboot your system because it will "hang". You can save a significant amount of development time if you locate in your source code where you want to place calls to functions in CTRLCLIB and then comment them out so they won't compile. Remove the comments when you are ready to ENABLE or DISABLE the interrupt handlers. One of the benefits of using functions from CTRLCLIB is interrupt feedback. By placing critical tests in your keyboard _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 26 CTRLCLIB - The Ctrl+C Library input routines you can detect user-initiated interrupts. We suggest your program ALWAYS test for the break keys and allow the user a graceful exit from your program. Try to sense the user's need to exit quickly and provide feedback to them. Tell them for example: "CTRL-C detected - cleaning up" and then allow your program to perform its cleanup functions such as emptying buffers, closing files, and freeing memory. You give the user what they want - a quick exit - but, under your full control. Complete management of, and communications between CTRLCLIB functions is handled by variables declared in the CTRLC.H header file. This is how various functions in the library can track interrupts that have been installed. It is not advisable to allow your program to manipulate the contents of these variables directly. The user of your application program may find their systems "hung" at termination time because your program modified something that the interrupt management functions needed to know about to properly reset an interrupt vector. If you are upgrading from a previous version of CTRLCLIB be sure to re-compile and re-link all of the source modules in your application that call functions from the Library. This will eliminate the possibility of any "unusual" problems. The libraries were created on an AST 386/20 under DOS 3.3 using Microsoft 5.1, Microsoft 6.0, Microsoft QuickC 2.5, Borland's Turbo C 2.0, and Turbo-C++ 1.0. Each compiler's own "LIB" facility was used to create each associated library. The test hardware included the following: AST 386/20, IBM PC/XT/AT, DELL 386/25. Additionally, a wide variety of clones (8088, 8086, 80186, 80286, 80386) with brand name and noname components were also tested. 8.1 Borland Turbo C Notes Integrated Development Environment users should create PROJECT files in order to be able to create executable programs from within the IDE. The PROJECT file must contain the names of all of the programs that comprise the application along with specific entries for all third party libraries being used. In the case of third party libraries, the complete path specification for the library must be provided (e.g. c:\tc\lib\stc20cl.lib). The control-c keystrokes will not be recognized by signal() and ctrlbrk(). However, since your program will get feedback _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 27 CTRLCLIB - The Ctrl+C Library from functions in CTRLCLIB if these keys are pressed, it won't be necessary to use these standard library functions. If your testing your program within the IDE environment you should comment out any CTRLCLIB functions since their use can cause unpredictable results in these environments. When you're ready to test your program as a stand-alone (i.e. outside of the IDE environment) - then you can un-comment the functions. 8.2 Microsoft C Notes Microsoft Version 5.1 and Version 6.0 libraries were generated using the "/Zl" command line parameter. This should insure compatibility with previous versions of the compiler. 8.3 Microsoft QuickC Notes Quick-C Programming Environment users should create MAKE files in order to be able to create executable programs from within the Programming Environment. The MAKE file must contain the names of all of the programs that comprise the application along with specific entries for all third party libraries being used. 8.4 MS-DOS Notes The CtrlC() function is a superset function and includes trapping CTRL+BREAK; however, the code returned by QueryCtrlC() is ALWAYS "CTRLC" because CTRL+BREAK generates a ^C character which DOS gets a hold of and indicates a 'break'. ALSO note that the infamous ^C characters are printed on the screen by DOS when using PRINTF in C. If you want to prevent this, use the FullCtrlC() function. Disabling CTRL+BREAK *ONLY* will NOT disable CTRL+C. Typing a CTRL+C (or CTRL+2) on the keyboard will definitely break the user out of your program and NOT restore the CTRL+BREAK interrupt vector. Note too that if your program only disables CTRL+BREAK and the user presses CTRL+BREAK, the interrupt will NOT generate the infamous ^C on the screen as CTRL+C will do. However, pressing CTRL+C with just the CTRL+BREAK handler installed will generate the ^C and return the user to DOS and hang the users' system because the CTRL+BREAK vector will NOT get properly restored. _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 28 CTRLCLIB - The Ctrl+C Library 8.5 General Caveats 8.5.1 Keyboard Idiosyncrasies Some of the following problems and idiosyncrasies that were reported by alpha and beta testers during development of this library. We report them here because they are not mainstream problems, but rare oddities and quirks unique to certain keyboards. If you're concerned about these, remember - when you register, you'll get full source code to work with so you'll be able to program for these oddities. Tandy computers and keyboards of the TL and TX models seem to be a real problem. With a third party video card installed and the IEMSEMM.SYS EMS driver installed, the machine will not respond to the CTRL+ALT+DEL reboot. Additionally, the machine will not respond to a programmed reboot (SystemReset function). If the video card is removed and the default hardwired TANDY 16 color is used with a CGA monitor and EMS driver removed then CTRL+ALT+DEL works fine as well as the internal system reset call (SystemReset function). This code won't work with the IEMSEMM.SYS EMS driver installed. The machine will get to the point where it tries to load the driver then hangs. This may be a problem with this particular EMS driver. The following code is needed to make the machine reboot with EGA: mov bx,1234 mov ax,0040' mov ds,ax mov [0072],bx jmp f000:e465 The Tandy keyboard (as well as some others) has "hardwired" LED lights. That is, they respond only when the lock keys are physically pressed. They don't respond programmatically to the setting of the keyboard flags in the BIOS. If your program uses the lock key functions there is no guarantee that the LED status will reflect your programmed setting. However, the functionality will be there. i.e. if you set a lock key to L_ON, it will be on, and the keystroke entered will reflect the status of the lock key - Capital A with caps lock set to L_ON, etc. even though the LED light may be off. _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 29 CTRLCLIB - The Ctrl+C Library Apparently some models of TANDY don't have a PAUSE key and the CTRL+NUMLOCK keys won't pause the system either. The HOLD button acts like the pause key and can be trapped. There are several other keyboards that act the same way. Also, we found that the user can defeat the use of the L_ALWAYSON setting. For example, if your program sets the caps lock key to L_ALWAYSON, the user can type lower case characters by pressing and HOLDING DOWN the SHIFT keys to type lower case characters. This is normal procedure anyway since the keyboard was engineered to respond that way. The Heathkit H-150 has the same problems as the Tandy with regard to the pause keys and keyboard LED lights. One tester reported the PRINTSCREEN key on a Northgate OmniKey/Plus had to be pressed twice to get the CLDEMO.EXE program (Test 9,10,11) to respond. This may be a problem with the demo program , but the functionality of blocking PRINTSCREEN will still be preserved. Although another user with a Northgate didn't report the problem. This problem did not occur on DELL or AST extended keyboards. Early DELL computers with the PHOENIX bios has a bug in the way the mode lights are handled by the controller. When your program sets the NUMLOCK to "L_ALWAYSON" you will ALWAYS get a number returned when any keypad number key is pressed. HOWEVER, if you press the NUMLOCK key, the light goes out! And - you will still get numerics from keypad keypresses. These subsequent keypresses will turn the mode light back on. Even though the mode lights are messed up - the program functionality is retained. 8.5.2 Virtual Control Programs 8.5.2.1 WINDOWS, DESQview, VM386, OS/2, et al There are some important functions provided by CTRLCLIB that simply will not work under some or all of these types of control programs. Applications will run as sub-tasks under these multi- tasking systems, so if they use functions from CTRLCLIB there's no guarantee that they will work properly. This is because some of the more powerful functions like capturing control-c, blocking ctrl-alt-delete, etc. are controlled by our INT09 ISR (Interrupt Service Routine). Many control programs reset their ISR's if they've found to be replaced which means the functionality is lost to a certain extent because they are usually replaced with an equivalent provided by the control program. _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 30 CTRLCLIB - The Ctrl+C Library Under Microsoft Windows, virtually all of the key sequences that can be captured and blocked by functions in CTRLCLIB are already suitably controlled by Windows. However, the LOCK keys can still be controlled. Under DESQview, the CTRL+ALT+DEL reboot sequence is captured and serves to close the current window. The CTRL+NUMLOCK sequence, which is the PAUSE on XT keyboards but not on extended keyboards will still PAUSE the system under DESQview. The CTRL+ALT+DEL sequence trap does not appear to work when running the CLDEMO program in a DOS box under Windows. 8.5.3 Other Caveats 8.5.3.1 TSR's o There is a minor problem with the Shareware TSR program called "CTRLALT". When "popped up", CTRLALT modifies the keypad such that ALT+1 produces a lower left box character (equivalent to ALT+192; ALT+2 is the lower line, and ALT+3 is the right corner. With your program loaded and running with full control-c suppression (function FullCtrlC), ALT+3 keypress will not be passed to CTRLALT to draw the lower right corner. o The use of a TSR called KBFIX produces interesting results in TEST 16 of the CLDEMO program. If you press ScrollLock, the system pauses. Then, if you press Enter a few times nothing happens. When you press ScrollLock again, the Enter's get released all at once which appears to be KBFIX's normal behavior. o Regarding controlling of the CapsLock, NumLock, ScrollLock, and such, popping into SIDEKICK PLUS allows one to release the locks (by pressing their keys *twice*). With CapsLock, for example, you can pop back down to CLDEMO, press the letter a key and get a lower-case "a" echoed to the screen. At that point, the CapsLock light does go back on again. NOTE: Please remember - these caveats were reported when using the demo program. The demo program was especially set up to provide feedback to the evaluator. Except for some physical _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 31 CTRLCLIB - The Ctrl+C Library keyboard design problems, NO CTRL+C LIBRARY FUNCTIONALITY IS LOST! You can use each function for its intended purpose. 8.6 Making Changes Incorporating local modifications or enhancements is, in part, why you acquired the source code for CTRLCLIB to begin with. Incorporating your modifications or enhancements should be a relatively straight forward task. Please study and understand the code before attempting modifications. Remember there is a lot of communication going on between the functions. If you feel you have developed a significant enhancement that would be useful and is well written and documented please let us know. We have often incorporated customer supplied enhancements to our products. Contact us for further details. 8.7 Feedback PLEASE - Pass along your comments to us. CTRLCLIB is a powerful tool for making your application programs "user-proof". If you find any logic errors please let us know. We are committed to making CTRLCLIB a standard "tool" in the MS-DOS programmer's toolbox at the best price available. If you have an idea for a new function or a way to improve an existing one, then please call, write, fax, or if you prefer, you can reach us via CompuServe. Our CompuServe electronic mail ID is [76210,771]. We will consider all requests and ideas. Lastly, if you use CTRLCLIB, register your copy and get the complete source code. The Shareware System will only work if you support it! _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 32 CTRLCLIB - The Ctrl+C Library 9. FUNCTION CALL REFERENCE SECTION CTRLCLIB - Function Calls (listed alphabetically) _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 33 CTRLCLIB - The Ctrl+C Library Summary 9.1 int BreakFlag( action, flagset ) int action; int flagset; Description The BreakFlag function can be used to set or interrogate the status of CTRL+C checking by MS-DOS. MS-DOS normally checks for the pressing of CTRL+C only when performing certain tasks. When CTRL+C checking is enabled, MS-DOS will check for CTRL+C during ANY function request. The BREAK command is normally used in the config.sys file to establish the degree of checking by MS-DOS for the CTRL+BREAK keypress. The default setting - BREAK OFF means that MS-DOS will only check for CTRL+BREAK during keyboard and screen I/O. BREAK ON lets MS-DOS check for the CTRL+BREAK keypress during ANY MS- DOS function. The application program can override the "BREAK ON" or BREAK OFF" command by issuing a BreakFlag function call to check the current status, and then changing the setting of the flag accordingly. "action" is a constant and can be either GETBREAKFLAG or SETBREAKFLAG. "flagset" must contain a zero or non-zero value. "flagset" is ignored if the "action" is GETBREAKFLAG. If the "action" is SETBREAKFLAG, and "flagset" is a non-zero value, the break flag will be set to the equivalent of "BREAK ON" and will enable MS-DOS to check for the CTRL+BREAK keypress during all function requests. Return Value The return value is the current effective setting of the flag. Usage i = BreakFlag(GETBREAKFLAG,0); //Interrogate current setting i = BreakFlag(SETBREAKFLAG,1); // Same as BREAK ON i = BreakFlag(SETBREAKFLAG,0); // Same as BREAK OFF Additional Notes and Cautions This is useful for applications doing extensive file I/O that requires a degree of control over MS-DOS's break checking rules. See Also: FullCtrlC(), CtrlBreak(), CtrlC() _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 34 CTRLCLIB - The Ctrl+C Library Summary 9.2 int CapsLock( setting ) int setting; Description The CapsLock function provides a number of different ways a program can manage the status of the keyboard CAPS LOCK key. The "setting" must be one of the CONSTANTS listed below. A setting of NULL or zero will return the previous CapsLock() setting of the CAPS LOCK key. "setting" is one of the following constants: CONSTANTS Meaning ------------------------------------------------------- L_OFF Turns CAPS LOCK off L_ON Turns CAPS LOCK on L_ALWAYSOFF Turn CAPS LOCK off and keep it off; user cannot turn the CAPS LOCK key on L_ALWAYSON Turn CAPS LOCK on and keep it on; user cannot turn the CAPS LOCK key off L_TOGGLE Reverses the setting of the CAPS LOCK key; if it was ON, it will be turned off, and visa versa. zero or NULL Return previous setting Return Value CapsLock() returns the functions' previous setting. It will return zero the first time it is called. It will also return zero or the previous setting if it was called with an invalid CONSTANT. Additional Notes and Cautions This function returns the setting as it was set by a previous call to this function. It does NOT return the current status of the CAPS LOCK key as it is currently set in the _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 35 CTRLCLIB - The Ctrl+C Library keyboard FLAG bytes. If this function was never previously called, it will return a zero. Before using the L_TOGGLE parameter, the program should set the key to some known state such as L_OFF or L_ON. Behavior of the keyboard with regard to the NEXT keystroke is unpredictable if CapsLock() is called with L_TOGGLE after an L_ALWAYSON or L_ALWAYSOFF setting. Use L_OFF to remove the permanent L_ALWAYSOFF or L_ALWAYSON setting. The L_ALWAYSOFF and L_ALWAYSON settings will cause the Keyboard Handler to be installed. You MUST call CapsLock(L_OFF) or CtrlcLibCleanup() to remove it prior to an exit() or abort() function call. See Also NumLock(), ScrollLock(), InsertLock() _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 36 CTRLCLIB - The Ctrl+C Library Summary 9.3 int CtrlcLibSetup(varg) unsigned int varg; Description The CtrlcLibSetup() function can be used as a shortcut to install all the desired interrupt handlers and traps that you need in a single function call. By OR'ing together some or all of the CONSTANTS listed below, this function will install each one listed. The corresponding function CtrlcLibCleanup() must be called prior to any programmed exit or abort. CONSTANTS Meaning ------------------------------------------------------- FCTRLC Install full CTRL+C and CTRL-BREAK interrupt management CTRLALTDEL Install system reset interrupt management control PAUSEKEY Prevent use of the PAUSE key or CTRL+NUMLOCK to pause the system CTRLS Prevent use of CTRL+S to pause printing to the screen CTRLP Prevent line echo to the printer PRINTSCREEN Prevent screen dump to the printer SYSREQ Trap the SYSREQ keypress CTRLC Trap the CTRL+C keypress and prevent program termination CTRLBREAK Trap the CTRL+BREAK keypress and prevent program termination (Note: FCTRLC includes CTRLC and CTRLBREAK) Return Value CtrlcLibSetup() returns a count of the number of traps and handlers installed. Additional Notes and Cautions _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 37 CTRLCLIB - The Ctrl+C Library Using FCTRLC will install the Keyboard Handler to prevent the ^C character from entering the keyboard buffer. FCTRLC will also trap the CTRL+C and CTRL+BREAK keypress. Use of FCTRLC with either/or CTRLC or CTRLBREAK is redundant and unnecessary. See Also CtrlcLibCleanup() Example #include <stdio.h> #define MAINL #include "ctrlc.h" void main(void) { int i; i = CtrlcLibSetup( FCTRLC | CTRLALTDEL | PAUSEKEY | SYSREQ ); . . . CtrlcLibCleanup(); exit(0); } _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 38 CTRLCLIB - The Ctrl+C Library Summary 9.4 void CtrlcLibCleanup( void ) Description The CtrlcLibCleanup function will remove all interrupt management routines that your application may have installed, and additionally, will reset all the LOCK keys to off. Return Value There is no return value from this function. Additional Notes and Cautions CtrlcLibCleanup() can be called whether or not CtrlcLibSetup() was used to initialize interrupt management. If separate interrupt management functions were used to trap keys, CtrlcLibCleanup() can be used instead of re-issuing separate function calls to remove them. Be aware that calling CtrlcLibCleanup will increase your programs code size because this function call causes ALL of CTRLCLIB interrupt management routines to be linked into your program whether you use them or not. All interrupt management functions are called inside of CtrlcLibCleanup() with the argument of "ENABLE" or "REMOVE". The functions are robust enough to know if they've been installed or not, so you don't have to worry about missing an interrupt. See Also CtrlcLibSetup() _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 39 CTRLCLIB - The Ctrl+C Library Summary 9.5 void CtrlAltDel( action ) int action; Description The CtrlAltDel function call installs the Keyboard Handler to trap the CTRL+ALT+DEL keypress action of the user. The CTRL+ALT+DEL is the standard system reset keypress sequence. "action" is one of the following CONSTANTS: CONSTANTS Meaning ------------------------------------------------------- DISABLE Traps the Ctrl+Alt+Del keypress and prevents a system reset by the user. ENABLE Returns full functionality to the Ctrl+Alt+Del system reset keys. Return Value There is no return value. Additional Notes and Cautions The program can check if these keys were pressed by examining the variable "cl.BootFlag" for a non-zero value. If desired, your program can then perform an "orderly" shutdown - closing files, cleaning up work areas, etc., then call SystemReset() to force a reboot. See Also SystemReset() _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 40 CTRLCLIB - The Ctrl+C Library Summary 9.6 void CtrlBreak( action ) int action; Description The CtrlBreak function call installs an interrupt management function to intercept the CTRL+BREAK keypress by the user. "action" is one of the following CONSTANTS: CONSTANTS Meaning ------------------------------------------------------- DISABLE Traps the Ctrl+Break keypress and prevents program termination. ENABLE Returns full functionality to the Ctrl+Break keypress. Return Value There is no return value. Additional Notes and Cautions Using CtrlBreak by itself will only trap the CTRL+BREAK keypress. The "^C" code will still be echo'ed to the screen by MS-DOS. The application program can examine the variable cl.BreakFlag or use QueryCtrlC() to see if this key was pressed by the user. See Also CtrlC(), FullCtrlC(), QueryCtrlC() _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 41 CTRLCLIB - The Ctrl+C Library Summary 9.7 void CtrlC( action ) int action; Description The CtrlC function installs an interrupt management routine to intercept the CTRL+C keypress by the user. "action" is one of the following CONSTANTS: CONSTANTS Meaning ------------------------------------------------------- DISABLE Traps the Ctrl+C keypress and prevents program termination. ENABLE Returns full functionality to the Ctrl+C keys. Return Value There is no return value. Additional Notes and Cautions Using CtrlC by itself will only trap the CTRL+C keypress. The "^C" code will still be echo'ed to the screen by MS-DOS. Additionally, if the CTRL+BREAK key is pressed AND the CtrlBreak interrupt management function was NOT installed, then the control-break keypress will act like control-c and cause program termination. See Also CtrlC(), FullCtrlC(), QueryCtrlC() _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 42 CTRLCLIB - The Ctrl+C Library Summary 9.8 void CtrlP( action ) int action; Description The CtrlP interrupt management function will capture the CTRL+PRTSCRN and the CTRL+P keypresses. These keypresses by the user normally cause STDOUT output to the screen to be echo'ed line-by-line to the attached printer. "action" is one of the following CONSTANTS: CONSTANTS Meaning ------------------------------------------------------- DISABLE Traps the Ctrl+P and Ctrl+PrintScreen keypress and prevents MS-DOS from echoing screen lines to the printer ENABLE Returns full functionality to the Ctrl+P and Ctrl+PrintScreen keys. Return Value There is no return value. Additional Notes and Cautions Use QueryPrtScrn() to determine which set of print keys were pressed. See Also PrintScreen(), QueryPrtScrn() _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 43 CTRLCLIB - The Ctrl+C Library Summary 9.9 void CtrlS( action) int action; Description When the user presses the CTRL+S keys, MS-DOS output to the screen is halted temporarily until any typing key is pressed. The CtrlS interrupt management function will capture the CTRL+S keypress by the user thus preventing printing to the screen to be paused. "action" is one of the following CONSTANTS: CONSTANTS Meaning ------------------------------------------------------- DISABLE Traps the Ctrl+S pause to STDOUT ENABLE Returns full functionality to the Ctrl+S keys. Return Value There is no return value. Additional Notes The application program can examine the variable named cl.PauseFlag in the control structure to see if the user pressed CTRL+S. See Also PauseKey() _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 44 CTRLCLIB - The Ctrl+C Library Summary 9.10 void FullCtrlC( action ) int action; Description The FullCtrlC interrupt management function will prevent the user from breaking out of the application program when the CTRL+BREAK or the CTRL+C keys are pressed. This function will also prevent MS-DOS from echoing the "^C" characters to the screen. "action" is one of the following CONSTANTS: CONSTANTS Meaning ------------------------------------------------------- DISABLE Traps the Control-C, Alt+kp3, Control-2 keypress, plus control- break and prevents program termination. ENABLE Returns full functionality to these program break keys. Return Value There is no return value. Additional Notes and Cautions The application program can issue the function call QueryCtrlC() to determine which keys were pressed. See Also CtrlC(), CtrlBreak(), QueryCtrlC() _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 45 CTRLCLIB - The Ctrl+C Library Summary 9.11 int InsertLock( setting) int setting; Description The InsertLock function provides a number of different ways a program can manage the status of the keyboard INSERT key. The INSERT key is the keypad zero ( 0 ) key on ALL keyboards. On the 101 key keyboard it is also a separate key located above the DELETE key in the cursor movement key area between the main typing area and the keypad area. The INSERT key has no mode light to indicate a "LOCKED" or "ON" condition. The "setting" must be one of the CONSTANTS listed below. A setting of NULL or zero will return the previous InsertLock() setting of the INSERT LOCK key. CONSTANTS Meaning ------------------------------------------------------- L_OFF Turns INSERT key off L_ON Turns INSERT key on L_ALWAYSOFF Turn INSERT key off and keep it off; user cannot turn the INSERT key on L_ALWAYSON Turn INSERT key on and keep it on; user cannot turn the INSERT LOCK key off L_TOGGLE Reverses the setting of the INSERT key; if it was ON, it will be turned off, and visa versa. 0 or NULL Return previous setting Return Value InsertLock() returns the functions' previous setting. It will return zero the first time it is called. It will also return zero or the previous setting if it was called with an invalid CONSTANT. Additional Notes and Cautions _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 46 CTRLCLIB - The Ctrl+C Library This function returns the setting of the INSERT key as it was set by a previous call to this function. Before using the L_TOGGLE parameter, the program should set the INSERT key to some known state such as L_OFF or L_ON. Behavior of the keyboard with regard to the NEXT keystroke is unpredictable if InsertLock is called with L_TOGGLE after an L_ALWAYSON or L_ALWAYSOFF setting. Use L_OFF to remove the permanent L_ALWAYSOFF or L_ALWAYSON setting. The L_ALWAYSOFF and L_ALWAYSON settings will cause the Keyboard Handler to be installed. You MUST call InsertLock(L_OFF) or CtrlcLibCleanup() to remove it prior to a standard library exit() or abort() function call. See Also NumLock(), CapsLock(), ScrollLock() Example void main(void) { InsertLock(L_ALWAYSON); /* keep caps lock ON */ . . . InsertLock(L_OFF); /* unlock the caps lock key */ exit(0); } _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 47 CTRLCLIB - The Ctrl+C Library Summary 9.12 void KeyboardHandler( action ) int action; Description The KeyboardHandler function installs an INT09 interrupt service routine to handle keyboard make/break codes. This is a low-level routine that is called by most of the other interrupt management functions when the trapping of certain keypresses requires this routine to be called. The INSTALL action will replace the BIOS INT09 with KeyboardVector, the actual ISR. The REMOVE action will restore the original BIOS INT09. Return Value There is no return value. Additional Notes and Cautions The application program should never call this function directly. Use the interrupt management functions for the specific keys to be trapped. These functions in turn, will call KeyboardHandler(). If the application program installs the INT09 interrupt service routine with KeyboardHandler, then it must use either KeyboardHandler with the REMOVE parameter or call CtrlcLibCleanup(). See Also n/a _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 48 CTRLCLIB - The Ctrl+C Library Summary 9.13 int NumLock( setting ) int setting; Description The NumLock function provides a number of different ways a program can manage the status of the keyboard NUM LOCK key. The Num-Lock key, when locked on will cause keypresses of the keypad keys to send the ASCII numbers 0 thru 9 to the keyboard buffer area. When the NUM LOCK key is off, the keypresses will send cursor movement characters to the keyboard buffer. On more advanced keyboards, the NUM LOCK key has a mode light to indicate a "LOCKED" or "ON" condition. The "setting" must be one of the CONSTANTS listed below. A setting of NULL or zero will return the previous NumLock() setting of the NUM LOCK key. CONSTANTS Meaning ------------------------------------------------------- L_OFF Turns NUM LOCK off L_ON Turns NUM LOCK on L_ALWAYSOFF Turn NUM LOCK off and keep it off; user cannot turn the NUM LOCK key on L_ALWAYSON Turn NUM LOCK on and keep it on; user cannot turn the NUM LOCK key off L_TOGGLE Reverses the setting of the NUM LOCK key; if it was ON, it will be turned off, and visa versa. 0 or NULL Return previous setting Return Value NumLock() returns the functions' previous setting. It will return zero the first time it is called. It will also return zero or the previous setting if it was called with an invalid CONSTANT. Additional Notes and Cautions _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 49 CTRLCLIB - The Ctrl+C Library This function returns the setting of the NUM LOCK key as it was set by a previous call to this function. Before using the L_TOGGLE parameter, the program should set the NUM LOCK key to some known state such as L_OFF or L_ON. Behavior of the keyboard with regard to the NEXT keystroke is unpredictable if NumLock is called with L_TOGGLE after an L_ALWAYSON or L_ALWAYSOFF setting. Use L_OFF to remove the permanent L_ALWAYSOFF or L_ALWAYSON setting. The L_ALWAYSOFF and L_ALWAYSON settings will cause the Keyboard Handler to be installed. You MUST call NumLock(L_OFF) or CtrlcLibCleanup() to remove it prior to a standard library exit() or abort() function call. See Also CapsLock(), ScrollLock(), InsertLock() _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 50 CTRLCLIB - The Ctrl+C Library Summary 9.14 void PauseKey( action ) int action; Description The PauseKey interrupt management function resets the effect of a keypress of the PAUSE key or the CTRL+NUMLOCK keys. These keys cause the system to pause all processing. When pressed, a flag is set in the BIOS and the BIOS keyboard handler will loop internally until the flag is reset by another keypress. The DISABLE action installs a timer interrupt handler that will reset the internal hold flag every time the pause key is pressed. The ENABLE action will remove the interrupt handler and restore the capability of the pause key to pause the system. "action" is one of the following CONSTANTS: CONSTANTS Meaning ------------------------------------------------------- DISABLE Install a timer interrupt to reset the "wait" bit whenever PAUSE is pressed ENABLE Returns full functionality to the PAUSE or CTRL-NUMLOCK key(s). Return Value There is no return value. Additional Notes and Cautions The PauseKey function will NOT trap the CTRL+S keypress by the user. The CTRL+S keys will only pause output to the screen or STDOUT. Use the CtrlS() function to trap these keys. The application program can test the cl.PauseFlag variable to determine if the PAUSE key was pressed by the user. See Also CtrlS() _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 51 CTRLCLIB - The Ctrl+C Library Summary 9.15 void PrintScreen( action ) int action; Description The PrintScreen function installs an interrupt management function that traps the PRINT SCREEN keypress sequence and disables the usual screen print to the printer. "action" is one of the following CONSTANTS: CONSTANTS Meaning ------------------------------------------------------- DISABLE Traps the PRINT SCREEN keypress and prevents a screen "dump" to the printer ENABLE Returns full functionality to the PRINT SCREEN key. Return Value There is no return value. Additional Notes and Cautions none See Also CtrlP() _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 52 CTRLCLIB - The Ctrl+C Library Summary 9.16 unsigned QueryCtrlC(void) Description The QueryCtrlC function returns the value of CTRLCLIB structure's "break" flag and at the same time resets it to zero. Return Value Returns a value indicating if the user pressed one of the "break" keys depending on the interrupt management functions installed: CTRLC The user pressed the CTRL+C keys. CTRLBREAK The user pressed the CTRL+BREAK keys CTRL2 The user pressed the CTRL+2 keys ALT3 The user pressed the ALT+Keypad 3 keys zero None of these keys were pressed. Additional Notes and Cautions The CTRL2 and ALT3 values will be returned ONLY if the FullCtrlC interrupt management function was called. See Also FullCtrlC(), CtrlC(), CtrlBreak() _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 53 CTRLCLIB - The Ctrl+C Library Summary 9.17 unsigned QueryKeyPad5(void) Description The QueryKeyPad5 function returns the value of CTRLCLIB structure's keypad 5 status flag and resets it to zero. Return Value Returns a boolean value indicating if the user pressed the key pad 5 key. The setting of the NUMLOCK key is irrelevant. KEYPAD5 The user pressed the Keypad 5 key. zero This key was not pressed. Additional Notes and Cautions none See Also n/a _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 54 CTRLCLIB - The Ctrl+C Library Summary 9.18 unsigned QueryPrtScr(void) Description The QueryPrtScr function returns the value of CTRLCLIB structure's print screen status flag and resets it to zero. Return Value Returns a value indicating if the user pressed any print screen function keys depending on the interrupt management functions installed: CTRLP The user pressed the CTRL+P keys. CTRLPRTSCR The user pressed the CTRL+PRTSCRN keys PRINTSCEEN The user pressed the PRINTSCREEN or zero None of these keys were pressed. Additional Notes and Cautions none See Also CtrlP() PrintScreen() _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 55 CTRLCLIB - The Ctrl+C Library Summary 9.19 unsigned QuerySysReq(void) Description The QuerySysReq function returns the value of CTRLCLIB structure's SysReq flag and at the same time resets it to zero. Return Value Returns a value indicating if the user pressed the SysReq key. SYSREQ The user pressed the SysReq key. zero This key was not pressed. Additional Notes and Cautions none See Also FullCtrlC(), CtrlC(), CtrlBreak() _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 56 CTRLCLIB - The Ctrl+C Library Summary 9.20 int ScrollLock( setting ) int setting; Description The ScrollLock function provides a variety of ways a program can manage the status of the keyboard SCROLL LOCK key. The "setting" must be one of the CONSTANTS listed below. A setting of NULL or zero will return the previous ScrollLock() setting of the SCROLL LOCK key. CONSTANTS Meaning ------------------------------------------------------- L_OFF Turns SCROLL LOCK off L_ON Turns SCROLL LOCK on L_ALWAYSOFF Turns SCROLL LOCK off and keeps it off; user cannot turn the SCROLL LOCK key on L_ALWAYSON Turns SCROLL LOCK on and keeps it on; user cannot turn the SCROLL LOCK key off L_TOGGLE Reverses the setting of the SCROLL LOCK key; if it was ON, it will be turned off, and visa versa. 0 or NULL Return the previous setting Return Value ScrollLock() returns the functions' previous setting. It will return zero the first time it is called. It will also return zero or the previous setting if it was called with an invalid CONSTANT. Additional Notes and Cautions This function returns the setting as it was set by a previous call to ScrollLock. If this function was not previously called, the first call to it will return a zero. Before using the L_TOGGLE parameter, the program should set the Scroll Lock key to some known state such as L_OFF or L_ON. _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 57 CTRLCLIB - The Ctrl+C Library Behavior of the keyboard with regard to the NEXT keystroke is unpredictable if ScrollLock is called with L_TOGGLE after an L_ALWAYSON or L_ALWAYSOFF setting. Use L_OFF to remove the permanent L_ALWAYSOFF or L_ALWAYSON setting. The L_ALWAYSOFF and L_ALWAYSON settings will cause the Keyboard Handler to be installed. You MUST call ScrollLock(L_OFF) or CtrlcLibCleanup() to remove it prior to a standard library exit() or abort() function call. See Also NumLock(), CapsLock(), InsertLock() _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 58 CTRLCLIB - The Ctrl+C Library Summary 9.21 void ShowCtrlC( void) Description This support function will print the "^C" characters on the display at the current cursor location. Return Value There is no return value Additional Notes and Cautions The ^C characters are followed by a carriage return character that positions the cursor at the beginning of the next line. Use this with FullCtrlC() to fully simulate a control- break. See Also FullCtrlC() CtrlC() CtrlBreak() _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 59 CTRLCLIB - The Ctrl+C Library Summary 9.22 void SysReq( action ) int action; Description The SysReq function installs an interrupt service routine that captures any keypress of the "SysReq" key. "action" is one of the following CONSTANTS: CONSTANTS Meaning ------------------------------------------------------- INSTALL Traps the SysReq keypress. Sets a flag when the user presses this key. REMOVE Returns full functionality to the SysReq key. Return Value There is no return value. Additional Notes and Cautions This function installs the Keyboard Handler, be sure to REMOVE the SysReq trap before program termination. Use the QuerySysReq function to determine if the user pressed the SysReq key. The return value of QuerySysReq is unpredictable if SysReq was never INSTALL'ed. See Also QuerySysReq() _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 60 CTRLCLIB - The Ctrl+C Library Summary 9.23 void SystemReset( action ) int action; Description Calling this function will cause the users PC to reboot according to the "action" requested. "action" is one of the following CONSTANTS: CONSTANTS Meaning ------------------------------------------------------- WARMBOOT Reset the PC and perform a warmboot; same as pressing the CTRL+ALT+DEL key sequence COLDBOOT Reset the PC and perform complete coldboot diagnostics followed by boot-up of MS-DOS. This is the same as turning the machine OFF then ON again. Return Value There is no return value. The system is reset. Additional Notes and Cautions This function should be used in conjunction with the CtrlAltDel() function to trap any user keypress of the system reset keys. See Also CtrlAltDel() _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 61 CTRLCLIB - The Ctrl+C Library 10. APPENDIX -A- LICENSE AND REGISTRATION 10.1 SHAREWARE LICENSE (a) This collection of object libraries, programs and files is referred to as "CTRLCLIB - The Ctrl+C Library". If you have received it without registering with Trendtech Corporation, you have the "Shareware Version" of CTRLCLIB, and the license in this section describes your permitted use of the software. If you have registered with Trendtech Corporation, your permitted use is described in the registration section below; in addition, you continue to have the right to distribute the Shareware Version of CTRLCLIB as described in this section. (b) CTRLCLIB is a commercial software package. It is not free, and it is not in the public domain. It is distributed as Shareware, which means that before you pay for the package, you may evaluate it and see if you want to continue using it. You may use CTRLCLIB free for a trial period of up to thirty (30) days. In order to continue use after that period, or include any part or all of this software as part of any saleable product, either commercial, shareware, or freeware, registration with Trendtech Corporation is required. Any such use of CTRLCLIB without registration is in violation of federal copyright laws and will be prosecuted to the fullest extent of the law. (c) (i) You may give complete, exact copies of the entire Shareware Version to others, either personally or through electronic distribution. They may also use and copy this Shareware Version under the terms of this Agreement. (ii) You may NOT distribute CTRLCLIB other than through exact, complete copies of the Shareware Version passed to friends and associates for their individual use, or distributed electronically. Among other things, you may not place CTRLCLIB or any part of the CTRLCLIB package in any user-group or commercial library without express written permission from Trendtech Corporation, and you may not distribute for a fee, or in any way sell copies of CTRLCLIB or any part of CTRLCLIB package without express written permission from Trendtech Corporation. Any other use of the _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 62 CTRLCLIB - The Ctrl+C Library Shareware Version by any person, business, corporation, government organization, or any other entity is strictly forbidden and is a violation of this license Agreement. (iii) The CTRLCLIB Shareware Version diskette, which contains a copy of this manual, may be freely copied and shared. But printed copies of this document may not be photocopied in any way without written permission from Trendtech Corporation. No copy of the software may be distributed or given away without this accompanying documentation; this notice must not be removed. ONLY COPIES OF THE SHAREWARE VERSION MAY BE DISTRIBUTED. THE REGISTERED VERSION OF THIS PROGRAM MAY NOT BE DISTRIBUTED IN ANY FORM EXCEPT AS EXPRESSLY DESCRIBED IN PARAGRAPH 3. If you do not agree with these terms and conditions, you do not have permission from the copyright holder, Trendtech Corporation, to use the Shareware Version of CTRLCLIB, and you must stop using it and remove it from your computer. Any use or distribution of CTRLCLIB which violates this license agreement will be considered a copyright violation, and prosecuted to the full extent of the law. 10.2 Warranty and Liability Information. 10.2.1 Shareware Version - Warranty Exclusion TRENDTECH CORPORATION LICENSES THE SOFTWARE AND MANUAL FOR THE SHAREWARE VERSION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. TRENDTECH CORPORATION DOES NOT WARRANT THAT THE SHAREWARE VERSION WILL MEET YOUR REQUIREMENTS, OR THAT THE OPERATION OF THE SHAREWARE VERSION WILL BE UNINTERRUPTED OR ERROR FREE. 10.2.2 Registered Version - Limited Warranty Trendtech Corporation warrants that CTRLCLIB diskette, source code and documentation distributed to registered users are free of physical defects, subject to the following: Trendtech Corporation will replace or refund the purchase price of the diskette and/or any other physical parts or components of CTRLCLIB found to be defective, if such defect is the fault of Trendtech Corporation and not the result of misuse or abuse, and if the defective items are returned to Trendtech Corporation _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 63 CTRLCLIB - The Ctrl+C Library within the warranty period of thirty (30) days after registration. TRENDTECH CORPORATION MAKES NO OTHER WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, AND TRENDTECH CORPORATION'S WARRANTY IS EXPRESSLY LIMITED TO THE COST OF REPLACEMENT OF ANY DEFECTIVE DISKETTE OR OTHER PART. 10.2.3 Liability Limitation IN NO EVENT WILL TRENDTECH CORPORATION BE LIABLE FOR CONSEQUENTIAL, INCIDENTAL, INDIRECT OR OTHER DAMAGES, INCLUDING ANY LOST PROFITS, LOST SAVINGS, OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF, OR INABILITY TO USE, THIS SOFTWARE, EVEN IF TRENDTECH CORPORATION HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY. 10.3 REGISTRATION We encourage you to register your copy of CTRLCLIB. The registration fee is $30.00 plus shipping and handling. Registration entitles you to several benefits: 1. A number-serialized diskette containing ALL of the SOURCE CODE in CTRLCLIB for all supported C compilers. 2. Free telephone and mail support. 3. Minimal fee updates. Minimal fees cover the cost of media, shipping, handling, and update preparation. See the section entitled Upgrade Policy in Appendix -C- for upgrade details. 4. Royalty-free distribution of compiled CTRLCLIB routines used within your own software products. 5. A license to use CTRLCLIB after the thirty day (30) trial period has expired. 6. Thanks from us for your support and encouragement! 10.3.1 Source Code _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 64 CTRLCLIB - The Ctrl+C Library All source code provided with the registered version of CTRLCLIB is provided for purposes of your internal use only. You may freely modify the source code as you please, and use it internally within the scope of your applicable internal use license, provided that the original copyright notice on CTRLCLIB in the form released by Trendtech Corporation must be included in all modified code. YOU MAY NOT DISTRIBUTE THE SOURCE CODE TO OTHERS UNDER ANY CIRCUMSTANCES, WHETHER OR NOT YOU HAVE MADE CHANGES TO IT." If you include some or all of the source code, in modified or unmodified form, within your own program as a functioning part of your program, then you may distribute as part of that program under the same terms as set forth in 3.2, 3.3, and 3.4 below. 10.3.2 Single-User License (a) Description. You become a registered user of CTRLCLIB when you pay the registration fee indicated below to Trendtech Corporation. The Single-User Registration fee for CTRLCLIB is as follows: U.S.A. - $30.00, plus $3.00 for shipping/handling Canada - $30.00, plus $5.00 for shipping/handling Overseas - $30.00, plus $10.00 for shipping/handling MASTERCARD and VISA credit cards are accepted. All paper payments (checks, M.O., Postal M.O., etc.) MUST be expressed in U.S. dollars and drawn on a U.S. bank. Others will be returned. These prices are only for the registered version of CTRLCLIB corresponding to the release of the Shareware Version in which this license Agreement is contained. Later releases of CTRLCLIB may have different registration fees, and Trendtech Corporation is not obligated to accept registrations for less than the fees applicable to the then-current release. (b) Internal Use. This "SINGLE-USER" license authorizes you to use CTRLCLIB on any computer system you may own or use on a regular basis, so long as CTRLCLIB is used on only one computer system at a time. You may also install it on a computer attached to a network, or remove it from one computer and install it on a different one, provided there is no possibility that a single copy of CTRLCLIB will be used on more than one computer at a time. _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 65 CTRLCLIB - The Ctrl+C Library (c) Distribution. You may distribute routines and programs that use functions from CTRLCLIB on the following terms only: (i) They may be distributed free of charge, but you must register your intended use with Trendtech Corporation BEFORE ANY distribution. (ii) They can be distributed only within your own computer programs, and not by themselves. (iii) They must be fully functioning parts of your own programs, and entirely unavailable to recipients of your programs as stand-alone parts of any software toolkit, library, or collection. (iv) Any program containing CTRLCLIB functions, routines or programs must be distributed in compiled form only. (v) Any program that you distribute containing CTRLCLIB functions, routines or programs must contain a copyright notice in the program code properly protecting Trendtech Corporation's copyrights in CTRLCLIB. If you are uncertain about proper copyright notice, please contact Trendtech Corporation for instructions." Except as set forth above, you may NOT give, sell, or otherwise transfer copies of the registered version of CTRLCLIB to any other person or business for any reason. You may copy your registered version of CTRLCLIB for backup purposes only. 10.3.3 Network License. (a) Description. You may register CTRLCLIB for use on a computer network or other multi-user computer system. A fully registered and paid-for copy of CTRLCLIB, according to the prices set forth in 3.1(a) above, is required for each workstation/"keyboard". (b) Internal Use. Usage of CTRLCLIB on a network or other multi user-system constitutes usage of it for each workstation/"keyboard" connected to the network, whether CTRLCLIB is used on each of the workstations or not. (c) Distribution. Same as 3.2 _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 66 CTRLCLIB - The Ctrl+C Library 10.3.4 Site License (a) Description. You may register CTRLCLIB for use at one or more "sites". A site is defined as a single building or group of buildings at the same public mailing address. (b) Internal Use. A site license allows unlimited INTERNAL use of CTRLCLIB, on any number of machines, at the specified location. Please contact TRENDTECH CORPORATION for a copy of our General Licensing Provisions and site license fee schedule. (c) Distribution. Same as 3.2 10.3.5 Retail Distribution Contact Trendtech Corporation for information about retail distribution of CTRLCLIB and discount schedules. 10.3.6 Sales Tax: Licenses purchased in the State of New Jersey are subject to applicable sales taxes. 10.4 OWNERSHIP You agree that Trendtech Corporation is the sole owner of all rights and interests in CTRLCLIB, including but not limited to all copyrights, trade secrets, and patents (to Licensor's knowledge) in CTRLCLIB. You agree that nothing in this Agreement shall cause Trendtech Corporation's ownership rights in CTRLCLIB to be reduced in any way, nor cause you to gain any ownership rights in CTRLCLIB. Licensee shall not copy, reproduce, distribute, display, or operate CTRLCLIB except as expressly provided herein, nor modify or attempt to modify CTRLCLIB in whole or in part. You further agree that any modified versions you may create of any source code routines or programs in CTRLCLIB are fully covered by all of the terms of this Agreement, and may not be used by you except as authorized in this Agreement. _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 67 CTRLCLIB - The Ctrl+C Library 11. APPENDIX -B- WHAT IS SHAREWARE The Shareware method of software distribution gives users a chance to try software before buying it by evaluating it for a period of time. If you try a Shareware program and continue using it, you are expected to register with the author or copyright holder. Individual Shareware products differ on details -- some request registration while others require it, and most specify a maximum evaluation period. With registration, and depending on the product you register, you will obtain anything from the simple right to continue using the software to an updated program with a printed manual. Shareware is NOT the same as public domain software; public domain software typically does NOT contain copyright notices by the author. Shareware, on the other hand IS COPYRIGHTED by the author! Copyright laws apply to BOTH Shareware as well as commercial software (software distributed in retail markets), and the copyright holder retains all rights, with a few specific exceptions as stated below. Shareware authors are accomplished programmers, just like commercial software authors, and the programs are of comparable, if not better, quality. (In both cases, there are good programs and bad ones!) The main difference is in the method of distribution. The author of a Shareware program specifically grants the right to copy and distribute the software, either to all and sundry computer users or to a specific group. For example, most Shareware authors require written permission before a disk vendor may copy and distribute their Shareware program. So, Shareware is a software "distribution method", not a "type" or "kind" of software. As a computer user, you should try to find software that suits your needs as well as your pocketbook, whether it's commercial or Shareware. The Shareware system accommodates your needs, because you can "try before you buy". And because the overhead is low, prices - in the form of registration fees are low also. Shareware has the ULTIMATE money-back guarantee -- "if you don't use the product, you don't pay for it". _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 68 CTRLCLIB - The Ctrl+C Library 12. APPENDIX -C- DISTRIBUTION REQUIREMENTS Any person, group, or organization who wants to distribute CTRLCLIB for any kind of remuneration must FIRST contact TRENDTECH CORPORATION by letter at the address below for distribution permission. Authorization will be granted to distributors and disk vendors recognized by the Association of Shareware Professionals (ASP) as adhering to its guidelines for Shareware distributors. These organizations are known as "Associate Members" of the ASP. Distribution to other vendors will be made on the basis of their understanding of Shareware principles. CTRLCLIB is a "Shareware"-distributed program and is provided at no charge to the user for evaluation. Any fees paid by you - the user, to organizations other than Trendtech Corporation are for their disk duplication and distribution services only. Trendtech Corporation receives NO PART of those fees. "For-Profit" disk vendors must obtain permission from Trendtech Corporation to distribute CTRLCLIB. All users are granted a limited license to copy the Shareware version of CTRLCLIB and give it to others without charge for their evaluation and trial use under the following conditions: - CTRLCLIB Shareware disk must be distributed in its original, unmodified, complete form, including all library files, documentation files, text files, files containing license agreements, registration fees and schedules, and Shareware information. - CTRLCLIB Shareware disk or any of its components, objects, or libraries may NOT be distributed in conjunction with any other product or service, without express written permission from Trendtech Corporation. - The serialized registered version of CTRLCLIB which contains source code, is NOT to be given to anyone, nor is it to be distributed under any circumstances. Backups may be made by the registered user for archival purposes only. Please send all requests and inquiries regarding distribution to the following address: TRENDTECH CORPORATION P.O. Box 3687 Wayne, NJ 07474-3687 USA - or - FAX: (201) 694-2543 _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 69 CTRLCLIB - The Ctrl+C Library 13. APPENDIX -D- REGISTRATION BENEFITS Registration of CTRLCLIB gives you many benefits: all registered users will receive a copy of the latest version of CTRLCLIB containing full C-Source code, libraries for all supported compilers and memory models, and free support from Trendtech Corporation by telephone or letter. Finally, the author's letter of sincere thanks for supporting Shareware will include an unconditional money-back-guarantee if you are not fully satisfied. The money-back-guarantee is limited to thirty (30) days from the date you receive the registered package. 13.1 Upgrade Policy Please be advised that Trendtech Corporation may or may not notify registered users directly of new versions of CTRLCLIB as we are constantly changing and improving the product. Notification, when necessary, may be made through direct mailing to registered users, publication of press releases, upgrade listings in disk vendor catalogs, ASP catalogs, vendor advertisements, etc. If registered users would like to keep current, they may send us their original registered disk (the one with our label and serial number on it) along with $5.00 to cover shipping and handling. Registered users will then receive a disk with the most current version of CTRLCLIB on it. We suggest you do this at least annually to benefit from significant software changes. Single-user registration fees, and requests for other kinds of licenses should be mailed to: TRENDTECH CORPORATION CTRLCLIB Registration P.O. Box 3687 Wayne, NJ 07474-3687 USA FAX: (201) 694-2543 Please take a moment to complete and mail the CTRLCLIB registration form. It is in a file on the disk called REGISTER.FRM and contains a SINGLE-USER License agreement and an order form. Be sure to specify the disk size needed. This action will register you as a bonafide user of CTRLCLIB and help us provide you with better service. _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 70 CTRLCLIB - The Ctrl+C Library 14. APPENDIX -E- THE A.S.P. William Letendre, the author of CTRLCLIB, and the PC-FASTYPE typing tutorials, along with his company TRENDTECH CORPORATION, are members of The Association of Shareware Professionals (ASP). The ASP was formed in 1987 to strengthen the future of "Shareware" (formerly known as user-supported software) as an alternative to software distributed under normal commercial marketing methods. The ASP has established stringent standards for both its author-members and any vending organization which has "ASP Approved" status. ASP members subscribe to a code of ethics and are committed to the concept of Shareware as a way of marketing their product. The ASP itself does NOT rate members' software for functionality or usefulness. That is for you "the user" to decide. Shareware-distributed-software, especially software authorized to carry the ASP name, can be tested by you on a try-before-you-buy basis. If, after the evaluation period, you determine the program doesn't fit your needs, you won't have to worry about getting a refund - simply don't register; that's the beauty of Shareware. 14.1 The ASP Ombudsman Statement The ASP wants to make sure the Shareware principle works for you. If you are unable to resolve a Shareware-related problem with an ASP member by contacting the member directly, the ASP may be able to help you. The ASP Ombudsman can help you resolve a dispute or problem with an ASP member, but does not provide technical support for members' products. Please write to the ASP Ombudsman at P.O. Box 5786, Bellevue, WA 98006, or send a CompuServe message via electronic MAIL to: ASP Ombudsman, CompuServe ID: 70007,3536 14.2 Summary of ASP Goals o To inform users about shareware programs and about shareware as a method of distributing and marketing software; o To encourage broader distribution of shareware through user groups and disk dealers who agree to identify and explain the nature of shareware; o To assist members in marketing their software; o To provide a forum through which ASP members may communicate, share ideas, and learn from each other; and _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 71 CTRLCLIB - The Ctrl+C Library o To foster a high degree of professionalism among shareware authors by setting programming, marketing, and support standards for ASP members to follow. 14.3 ASP Standards for Author Members 14.3.1 PROGRAMMING STANDARDS The program meets the ASP's definition of "shareware" (i.e., it is not a commercial demo with major feature disabled, nor a time- limited program). The program has been thoroughly tested by the author and should not be harmful to other files or hardware if used properly. 14.3.2 DOCUMENTATION STANDARDS Sufficient documentation is provided to allow the average user to try all the major functions of the program. Any discussion of the shareware concept and of registration requirements is done in a professional and positive manner. 14.3.3 SUPPORT STANDARDS The member will respond to users who send registration payments, as promised in the program's documentation. At a minimum, the member will acknowledge receipt of all payments. The member will establish a procedure for users to report, and have acknowledged, matters such as bug reports, and will describe such means in the documentation accompanying all versions of the programs. The author will respond to written bug reports from registered users when the user provides a self-addressed, stamped envelope. Known incompatibilities with other software or hardware and major or unusual program limitations are noted in the documentation that comes with the shareware (evaluation) program. _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 72 CTRLCLIB - The Ctrl+C Library 14.3.4 GENERAL Members will keep the ASP apprised of changes in mailing address; which shareware programs they have published and are currently supporting; the current version numbers; and of any changes in the status of their programs. If a user has a dispute with an ASP member-author, the user may appeal to the ASP to mediate for arbitration of the dispute. For more information about the Association of Shareware Professionals, write to: Membership Secretary, Association of Shareware Professionals, P.O. Box 5786, Bellevue, WA 98006. _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 73 CTRLCLIB - The Ctrl+C Library CTRLCLIB NOTES: _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc. Page 74 CTRLCLIB - The Ctrl+C Library _________________________________________________________________ Copyright 1990 Trendtech Corporation, Inc.